Chess Game Indexer with ChessQL Query Language

Adds a chess game indexing service that fetches games from chess.com, extracts tactical motifs (pins, forks, skewers, etc.), and provides a
SQL-like query language (ChessQL) for searching.

Features

Indexing Pipeline

• Fetches games from chess.com API by player and date range
• Parses PGN, replays positions using chariot library
• Detects 5 tactical motifs: pin, cross-pin, fork, skewer, discovered attack
• Stores game metadata and motif flags in H2 (in-process) or PostgreSQL

ChessQL Query Language

• SQL-like syntax: white.elo > 2500 AND motif(fork)
• Supports comparisons, IN clauses, boolean operators, motif functions
• Compiles to parameterized SQL (injection-safe)

In-Process Mode

• Runs with zero external dependencies using H2 in-memory database
• Useful for local dev, testing, CLI tooling, and demos

API

Index games

POST /index {"player":"hikaru","platform":"CHESS_COM","startMonth":"2026-01","endMonth":"2026-01"}

Check status

GET /index/{id}

Query with ChessQL

POST /query {"query":"motif(pin) AND white.elo > 2700","limit":10,"offset":0}

Architecture

HTTP API → InMemoryQueue → IndexWorker → H2/PostgreSQL
↓
FeatureExtractor → MotifDetectors

Test Coverage

• ChessQL: lexer, parser, SQL compiler
• Engine: PGN parser
• Motifs: fork, pin, skewer detectors
• Worker: result mapping (1-0, 0-1, 1/2-1/2)
• Queue: in-memory implementation

Documentation

• docs/API.md - REST API reference
• docs/CHESSQL.md - Query language grammar
• docs/DESIGN.md - Architecture overview
• docs/IN_PROCESS_MODE.md - Local development guide
• docs/ROADMAP.md - Future phases (validation, resilience, SQS, security)

Running Locally

INDEXER_DB_URL="jdbc:h2:mem:indexer;DB_CLOSE_DELAY=-1"
bazel run //jvm/src/main/java/com/muchq/indexer:indexer